Inside Macintosh: QuickDraw GX Programmer's Overview / Part 2 - The QuickDraw GX Programming Cookbook

Chapter 8 - Printing

Saving Printing Information

This programming recipe discusses how you can save the printing information stored in a document's job object along with the document. It also shows how to save an array specifying the custom format information for each page in
the document.

Overview of Recipe Steps

The steps in this recipe show you how to:

1. Save the information in a job object with its document
2. Save the page-to-format information
3. Restore a job object when opening a document
4. Restore the page-to-format information

You should follow each step of this recipe for any application that saves docu-
ments and allows users to specify printing information for those documents.

Functions Used in This Recipe

QuickDraw GX functions used in this recipe:

GXFlattenJobToHdl	"Core Printing Features" QuickDraw GX Printing
GXGetJobError	"Core Printing Features" QuickDraw GX Printing
GXCountJobFormats	"Page Formatting and Dialog Box Customization" QuickDraw GX Printing
GXGetJobFormat	"Core Printing Features" QuickDraw GX Printing
GXGetFormatCollection	"Page Formatting and Dialog Box Customization" QuickDraw GX Printing
GXUnflattenJobFromHdl	"Core Printing Features" QuickDraw GX Printing
AddCollectionItem	"Collection Manager" QuickDraw GX Environment and Utilities
GetCollectionItem	"Collection Manager" QuickDraw GX Environment and Utilities
GetCollectionItemInfo	"Collection Manager" QuickDraw GX Environment and Utilities

Standard Macintosh functions used in this recipe:

AddResource	"Resource Manager" More Macintosh Toolbox
WriteResource	"Resource Manager" More Macintosh Toolbox
UpdateResFile	"Resource Manager" More Macintosh Toolbox
HLock	"Memory Manager" Memory

This recipe gives a brief description of these functions; you can find complete reference information for these functions in the Inside Macintosh suite of books.

Recipe Step Descriptions

In this section each step is described individually.

1. Save the information in a job object with its document

   When the user saves a document, you should store the printing information in the document's job object so that when the user opens the document, you can restore its information.

   To store a job object to a file, you can flatten it into a handle using this code:

   Handle flatJobHandle;

   flatJobHandle = NewHandle(0);

   GXFlattenJobToHdl(gCurrent->documentJob, flatJobHandle);
   err = GXGetJobError(gCurrent->documentJob);

   Now you can store the contents of the handle into a resource in the document's file using the standard Macintosh functions AddResource, WriteResource, and UpdateResFile.

2. Save the page-to-format information

   The pageFormats array of your document information structure stores references to the page format object for each page of the document. You should save this information when saving a document, so that the custom page-formatting information that the user specified is not lost when the document is closed.

   You cannot save the references from the document's pageFormats array because the references may not be valid when the job object is unflattened. Fortunately, each format object associated with a job object has a unique format index value that will be valid when you unflatten the job object. You need to convert your array of format references to a list of format indexes. You can use this code:

   handle formatIndexes;

   / Code to allocate format index list memory goes here. */

   long fmt, pg;
   long totalFormats, fmtIdx;
   gxFormat currentFormat;
   long *lockedIndexArray;

   HLock(formatIndexes);
   lockedIndexArray = (long *) *formatIndexes;
   
   totalFormats = GXCountJobFormats[gCurrent->documentJob];

   for (fmtIdx = 2; fmtIdx <= totalFormats; fmtIdx++) {

       currentFormat = GXGetJobFormat(gCurrent->documentJob,
                                      curFormatIndex);

       for (pg = 1; pg <= gCurrent->numPages; pg++)
           if (gCurrent->pageFormat[pg -1] == fmtIdx)
               lockedIndexArray[pg - 1] = fmtIdx;

   }

   Now that you have format indexes rather than format object references, you can store them with your job object and they'll be valid when you restore your job object from disk.

   One easy way to store your list of format indexes is to include it as a collection item in the format collection object of your job's default format object. Then, when you flatten the job object, as you did in Step 1, QuickDraw GX includes your list in the flattened job, and so it is stored
   for you automatically.

   You can use this code to obtain a reference to the format collection object of the job's default format object:

   defaultFormat = GXGetJobFormat(gCurrent->documentJob, 1);

   defaultFmtCol = GXGetFormatCollection(defaultFormat);

   Then you can add your list of format indexes to the collection object using the Collection Manager's AddCollectionItem function. This code adds the list as an item in the collection:

   HLock(formatIndexes);

   AddCollectionItem(defaultFmtCol, 
                     kMyCollectionType, kMyCollectionID, 
                     GetHandleSize(formatIndexes),
                     *formatIndexes);

3. Restore a job object

   You can use the standard Macintosh function Get1Resource to read your flattened job object into a handle, and you can unflatten it using the function GXUnflattenJobFromHdl:

   GXUnflattenJobFromHdl(gCurrent->documentJob, flatJobHandle);

   If you saved your list of format indexes as in Step 2, then the GXUnflattenJobFromHdl function also restores that collection item for you. Step 4 shows how to convert the format index values into format references.

4. Restore the page-to-format information

   To restore your document's page-to-format information, you first need to obtain a reference to the collection object into which you saved your list of format indexes:

   defaultFormat = GXGetJobFormat(gCurrent->documentJob, 1);

   defaultFmtCol = GXGetFormatCollection(defaultFormat);

   Then you need to find the size of the list, create a handle to store it, and extract it from the collection object:

   GetCollectionItemInfo(defaultFmtCol, 
                         kMyCollectionType, kMyCollectionID,
                         dontWantIndex, 
                         &listSize,
                         dontWantAttrs);

   formatIndexes = NewHandle(listSize);

   HLock(formatIndexes);
   GetCollectionItem(defaultFmtCol, 
                     kMyCollectionType, kMyCollectionID,
                     dontWantSize, 
                     *formatIndexes);

   Finally, you can use this code to convert the indexes back into format object references:

   numPages = listSize / sizeof(long); 

   lockedIndexArray = (long *) *formatIndexes;

   for (pg = 0; (pg < numPages); pg++) {

      formatIndex = lockedIndexArray[pg];
      if (formatIndex != nil)
         formatReference = GXGetJobFormat(gCurrent->documentJob,
                                          formatIndex);
      else
         formatReference = nil;

      gCurrent->pageFormat[pg] = formatReference;
   }

   When you no longer need the handle referencing your list of format indexes, you can dispose of it using the standard Macintosh function DisposeHandle.

Related Recipes

For more information about printing with QuickDraw GX, see these recipes:

• "Managing Printing Information," beginning on page 253, which shows you how to create and dispose of job objects.
• "Handling Printing Dialog Boxes," beginning on page 257, which shows you how to display and respond to the printing dialog boxes.

Main | Page One | What's New | Apple Computer, Inc. | Find It | Contact Us | Help